<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 6.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Help Enhancements in Eclipse 3</title>
</head>

<body>

<h1 align="center">Help Enhancements in Eclipse 3.1</h1>
<p>This document describes new features added to provide for help and user 
assistance in Eclipse 3.1 release. The enhancements are still in progress and 
feedback is welcome. This document will be updated as changes are made towards 
the general availability of the release.</p>
<h2>Help View</h2>
<p>Most of the new help features revolve around the newly added Help view. The 
view is designed to be the universal location of most of the help needs inside 
the Eclipse workbench. The standard standalone help window from previous version 
is retained and is available via File&gt;Help Contents. The role of the view is to 
bring help contents closer to the user inside the perspective where most of the 
work is done.</p>
<p>The new Help view can show various classes of content in pages that are shown 
one at a time. The following classes are currently available: Related Topics, 
All Topics and Search.</p>
<h3>Related Topics</h3>
<p>This page shows help topics related to the current workbench context. It 
replaces the yellow info pop window when F1 is pressed in the workbench. It is 
also shown when context help is asked for programmatically. The topics 
include context help contributed via help context help extension point, as well 
as the result of a local help search on the query formed from the current 
context. For example, if the currently active workbench part is 'Package 
Explorer' inside the Java perspective, local help will be searched for (&quot;Package 
Explorer view&quot; OR &quot;Java perspective&quot;). The first few results will be shown in 
place, with the possibility to follow the link to more elaborate search.</p>
<p align="center">
<img border="0" src="related-topics.gif" width="275" height="705"></p>
<p>Related Topics page tracks changes in the workbench and updates accordingly. 
Workbench parts can affect the way Related Topics page works by supporting <code>
IContextProvider</code> interface. This interface defines how the page should 
react to the active part:</p>
<pre>public interface IContextProvider {
	/**
	 * State change trigger indicating a static context provider.
	 */
	int NONE = 0x0;

	/**
	 * State change trigger indicating that the provider should be asked for
	 * context help on each selection change.
	 */
	int SELECTION = 0x1;

	/**
	 * Returns the mask created by combining supported change triggers using the
	 * bitwise OR operation.
	 * 
	 * @return a bitwise-OR combination of state change triggers or
	 *         &lt;code&gt;NONE&lt;/code&gt; for a static provider.
	 */
	int getContextChangeMask();

	/**
	 * Returns a help context for the given target. The number of times this
	 * method will be called depends on the context change mask. Static context
	 * providers will be called each time the owner of the target is activated.
	 * If change triggers are used, the method will be called each time the
	 * trigger occurs.
	 * 
	 * @param target
	 *            the focus of the context help
	 * @return context help for the provided target or &lt;code&gt;null&lt;/code&gt; if
	 *         none is defined.
	 */
	IContext getContext(Object target);

	/**
	 * Returns a search expression that should be used to find more information
	 * about the current target. If provided, it can be used for background
	 * search.
	 * 
	 * @param target
	 *            the focus of the context help
	 * @return search expression as defined by the help system search, or
	 *         &lt;code&gt;null&lt;/code&gt; if background search is not desired.
	 */
	String getSearchExpression(Object target);
}</pre>
<p>Using the interface above can yield some interesting behavior. For example, 
if the context change mask is <code>SELECTION</code>, and <code>getContext</code> 
dynamically computes the context help for each selection, <b>Related Topics</b> 
will be highly dynamic. An example of this is support for Java editor where 
selections in the editor are reflected in the help view by showing the first 
sentence of Javadoc for the selected type.</p>
<h3>All Topics</h3>
<p>This page shows the Table of Contents tree you can also see in the classic <b>
Help</b> window. The native Tree widget is tweaked somewhat to continue the 
'web' user experience of the rest of the view. As a consequence, topics are 
opened on a single mouse click and cursor turns into a hand pointer when over 
the topics. However, tree item selections by the keyboard will not initiate the 
'open' action - one needs to press 'Enter' to view the topic. This behavior 
provides for the expected keyboard navigation and makes the tree close in 
behavior to the counterpart in the Help window.</p>
<p align="center">[<img border="0" src="all-topics.gif" width="278" height="709"></p>
<h3>Search</h3>
<p>One of the key new features in the new view is the <b>Search</b> page. The 
new mechanism supports federated search of multiple search engines running as 
background jobs. All engines run on the common search expression, but each 
engine's scope can be individually configured. Search expression follows certain 
rules that can be found when the label links above the text field is expanded:</p>
<p align="center">
<img border="0" src="expanded-expression.gif" width="276" height="202"></p>
<p>If the provided text is not sufficient, the help link should be followed to 
find more information.</p>
<h4>Search Types</h4>
<p>The new search support starts by providing the new extension point for 
contributing <b>engine types </b>(extension point id 'org.eclipse.help.ui.searchEngine'). An 
engine type is a proto-engine that can be 
instantiated and configured to perform a particular search. At the moment, 
Eclipse Help view provides three engine types out of the box:</p>
<ul>
	<li><b>Local Help</b> - searches the local help documentation. Instances of 
	this type 
	do not require any configuration.</li>
	<li><b>Info Center</b> - searches Eclipse help remote installation as Info 
	Center. Instances of this type require the remote server URL.</li>
	<li><b>Web Search</b> - searches a general-purpose Web search engine. 
	Instances of this type require the web search URL template with substitution 
	variable for the query.</li>
</ul>
<p>Most search needs can be satisfied by configuring one of the above search 
types. If that is not enough, new search types can be contributed using the 
above mentioned extension point. A good reason to contribute a new engine type is the existence 
of a separate domain where Eclipse users can find information for which there is 
a mechanism to issue complex queries and get results in a format suitable for 
parsing and presenting individually. For example, <b>Info Center</b> engine 
talks to the remote Web application to fetch the help books for scope 
configuration, as well as running the search and getting results in the XML 
format. If the remote search application does not provide results in a format 
that can be parsed, <b>Web Search</b> can be used to show the results in  
HTML format.</p>
<p>Instances of search engine types can be created in two ways:</p>
<ul>
	<li>Products can create engine instances as extension point contributions so 
	that they show up out of the box</li>
	<li>Users can create new engines by choosing from the list of available types 
	and configuring the selected engine type on the fly</li>
</ul>
<h4>Configuring engines</h4>
<p align="center">
<img border="0" src="scope-section.gif" width="275" height="323"></p>
<p>Users can influence the search outcome in several ways. The fastest way to 
tweak the search is to control which engine should run when 'Go' is pressed. 
This is done by expanding the 'Scope Settings' section and checking the engines 
that need to run. More detailed scope manipulation can be done when 'Advanced 
Settings' link is selected.</p>
<p align="center">
<img border="0" src="search-scope-local.gif" width="627" height="542"></p>
<p align="center">
<img border="0" src="search-scope-web.gif" width="628" height="542"></p>
<p>The scope settings dialog is similar to preference pages and has nodes for 
each configured search engine. Each engine has a page that contains the master 
switch (linked to the one exposed in the scope section) and other scope settings 
below it. The actual widgets for configuring scope settings depend on the engine 
type. Local Help and Info Center types provide for narrowing the scope by 
selecting particular books. Web search type provides the URL template that is 
executed when search is performed.</p>
<p>Users can add to the list of preconfigured engines by pressing the 'New...' 
button at the lower left edge of the dialog. This button brings up a dialog 
allowing users to choose the search engine type:</p>
<p align="center">
<img border="0" src="engine-types.gif" width="401" height="500"></p>
<p>All the settings made to the search engines are stored under one named 
preference set or <b>Scope Set</b>. Out of the box, the scope set that keeps the 
engine preferences is called 'Default'. By clicking on the scope name link in 
the <b>Search</b> page, it is possible to manipulate scope sets by creating new, 
editing and deleting them. Scope sets provide for quick switching between 
different search engine settings for all the configured engines at once.</p>
<p align="center"><img border="0" src="scope-sets.gif" width="320" height="376"></p>
<h4>Search results</h4>
<p>When engines are selected for search, search expression is entered and Go is 
pressed, Search page will start each engine as a separate background job. As 
results arrive, they will be shown below the scope section grouped by  
engine (subject to selection of the tool bar button
<img border="0" src="../../../org.eclipse.help.ui/icons/elcl16/desc_obj.gif" width="16" height="16">). Search results consist of entries that can be navigated to, and optional 
short description if the search engine supports it. When there are many results, 
the page is kept manageable by breaking results in to groups of 10 (this number 
will be configurable in the future). Search results can be shown flat, or 
additionally grouped by category (tool bar button
<img border="0" src="../../../org.eclipse.help.ui/icons/elcl16/show_categories.gif" width="16" height="16">), 
where category definition is provided by the results. For local help and Info 
Center, categories are books the results are coming from (e.g. Workbench User 
Guide, JDT ISV Guide etc.). Custom search engines can define their own 
categories.</p>
<p align="center">
<img border="0" src="search-results.gif" width="276" height="705"></p>
<h3>Document Link Navigation</h3>
<p>All the pages in the new Help view can be opened in two ways:</p>
<ul>
	<li>Internal-&nbsp; the page content will replace the content area of the 
	view (except the quick links at the bottom)</li>
	<li>External - the page will be shown in a separate window</li>
</ul>
<p>The actual choice between the two options is controlled by several factors:</p>
<ul>
	<li>If the creation of the embedded browser page fails or the embedded 
	browser in not supported on the particular OS, all links will be opened as 
	external.</li>
	<li>If the link represents a help topic, it will be shown as internal. 
	However, external window can be forced either from the link's pop-up menu or 
	(in case of search results) from the image link next to the topic. Topics 
	shown in the external window will be shown in the context of the help system 
	(with TOC).</li>
	<li>If the link represents a random URL, it will be shown as internal. If 
	external window is forced, it will be shown in a standalone web browser.</li>
	<li>Search result objects that implement <code>ISearchEngineResult</code> 
	interface can demand that their link is opened as external (see <code>
	ISearchEngineResult.getForceExternalWindow()).</code></li>
	<li>Help document shown inside the Help view can be opened in the external 
	mode by following the tool bar button <img border="0" src="browser.gif">.</li>
</ul>



<p align="center">
<img border="0" src="browser-part.gif" width="277" height="705"></p>



<table border="1" cellpadding="0" style="border-collapse: collapse" width="100%" id="table1" bgcolor="#CCFFCC" bordercolor="#000000">
	<tr>
		<td>An orthogonal effort is currently under way to provide Platform UI 
		support for showing URLs. URLs can be shown in a read-only web browser 
		editor or an external browser suitable for the current OS/WS 
		combination. When/if this support becomes available, the definition of 
		'External' in the context of Help view will be 'the page will be shown 
		in a separate <b>browser</b>'. Whether this browser opens in the editor 
		area or as a separate browser window will be user 
		preference.</td>
	</tr>
</table>



</body>

</html>